home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 081 / echodoc.arc / ECHOMAIL.DOC
Text File  |  1987-07-08  |  12KB  |  347 lines
  1.  
  2.                          EchoMail Technical Reference
  3.                          ----------------------------
  4.  
  5.  
  6.                               by Wynn Wagner III
  7.  
  8.                                  15-June-1987
  9.  
  10.                            
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19. ECHOMAIL SPECS AND STUFF
  20. ------------------------
  21.  
  22. EchoMail is a method of conferencing that uses the FidoNet<tm> protocol
  23. to broadcast messages.
  24.  
  25. The FidoNet<tm> protocol is determined by the International FidoNet
  26. Association ("IFNA").  That protocol involves the physical transmission 
  27. of files one system to another.
  28.  
  29. EchoMail itself is not affiliated with IFNA or any other association or
  30. organization.  It is a "grass-roots" concoction of fiercely independant
  31. system operators.
  32.  
  33. Because there is no association or organization, the EchoMail system
  34. relies on the goodwill of the sysops who use the system.  That means
  35. these "specs" and "rules" are totally voluntary.  There is no means
  36. for enforcement.
  37.  
  38. The word "SPECS" is probably out of place here.  You can consider this
  39. more like "Here's the way Opus does EchoMail."
  40.  
  41. When you see the word "message," it means a message prepared for
  42. transmission from one system to another.  The structure and content of
  43. a message as it lies on a local system is of no concern to anybody other
  44. than the system's software and sysop.
  45.  
  46.  
  47.  
  48.  
  49. IN-TRANSIT MESSAGE STRUCTURE
  50. ----------------------------
  51.  
  52.  
  53.          IN GENERAL
  54.          ----------
  55.  
  56.          All in-transit messages have two parts: header and body.  
  57.          
  58.          The header is defined by FidoNet<tm> specifications.  
  59.          
  60.          Those specifications describe the body of a message as being a 
  61.          null-terminated character array.  It could be that you will find
  62.          a 10k message that looks like a single line of text!  The
  63.          character 0x8D is treated as a "soft" return character so that
  64.          messages can be arranged at display-time to fit the user's
  65.          display.  A regular return character (0x0D) means what is says:
  66.          transmit a carraige return.
  67.  
  68.          For more information about the FidoNet<tm> protocol or the
  69.          message header, contact 220/1 in the matrix.
  70.  
  71.  
  72.  
  73.  
  74.          REQUIRED ECHOMAIL EXTENSIONS
  75.          ----------------------------
  76.  
  77.          EchoMail adds material at the beginning and the end of the 
  78.          message body.  
  79.          
  80.          There are four items which are absolutely required.  You can 
  81.          expect echomail processors to consider a problem with these four
  82.          items to be an error condition.
  83.  
  84.  
  85.  
  86.                   AREA STATEMENT
  87.                   --------------
  88.  
  89.                   When an echomail message is prepared for transmission, one
  90.                   piece of information is added: the AREA statement.  This
  91.                   statement normally does not appear in the message when it
  92.                   resides in the local message area.
  93.  
  94.                   The procedure is normally called "Scanning."
  95.  
  96.                   An AREA statement looks like this:
  97.  
  98.                            AREA:areaname
  99.  
  100.                   The "A" in "AREA" must be the zeroth character of the 
  101.                   message body... the first character following the 
  102.                   message header.
  103.  
  104.                   The word AREA is followed by a colon and the name of the
  105.                   area.
  106.  
  107.                   An areaname can be as long as 60 characters.  It is CASE 
  108.                   SENSITIVE and should always be uppercase.  The area name 
  109.                   can contain alphanumeric characters as well as the 
  110.                   underscore character.
  111.  
  112.                   The AREA statement always ends with a hard return.
  113.  
  114.                   Space characters are not part of an AREA statement.  
  115.                   (Utilities which handle inbound echomail should be 
  116.                   somewhat resiliant to messages containing space 
  117.                   characters after the colon.)
  118.  
  119.                            EXAMPLES:   AREA:SYSOP
  120.  
  121.                                        AREA:THE_ECHO_AREA_FOR_LIBERTARIANS
  122.  
  123.  
  124.  
  125.  
  126.                   TEARLINE 
  127.                   --------
  128.  
  129.                   A tearline is a gadget that separates the text of an
  130.                   echomail message from the echomail information appended
  131.                   to the message.
  132.                   
  133.                   It consists of a hard return, followed by three dashes, 
  134.                   optionally followed by an "scan program identifier.  
  135.                   The sequence ends with a hard return.
  136.  
  137.                                EXAMPLE 1:     -  -  -          ... ascii
  138.                                           0d 2d 2d 2d 0d       ... hex
  139.  
  140.                                EXAMPLE 2:  --- MyScanProg v1   ... ascii
  141.  
  142.  
  143.                   ORIGIN 
  144.                   ------
  145.  
  146.                   The origin line in a message shows the name of the
  147.                   system where the message was created.  Normally it
  148.                   includes the system name and its net/node number.
  149.                   
  150.                   It consists of a hard return, followed by a space, and
  151.                   asterisk, another space, the word "Origin", a colon, 
  152.                   the originating system's name, and a hard return.
  153.  
  154.                                EXAMPLE:  * Origin: Your Board Name
  155.  
  156.                                         That sequence begins like this:      
  157.  
  158.                                              0d 20 2a 20 4f
  159.  
  160.                                The word "Origin" is case SENSITIVE.  
  161.                                
  162.                                Spacing is not optional.
  163.  
  164.  
  165.  
  166.  
  167.                   SEEN-BY
  168.                   -------
  169.  
  170.                   The seen-by section is a sequence of one or more items
  171.                   that have this form:
  172.  
  173.                            SEEN-BY: net1/node1 [{net2/}node2 .. {netn/}noden]
  174.  
  175.                   The word "SEEN-BY" always follows a hard return (<cr> or
  176.                   <cr/lf>).  That is followed by colon and a space.  Then
  177.                   comes a list of matrix addresses.  Seen-by lines always
  178.                   end with a hard return and should be 80 characters or
  179.                   shorter.
  180.  
  181.                   An echomail message can contain more than one seen-by line.
  182.                   The seen-by area is always the last part of a message.
  183.  
  184.                   Except for the first address, the NET is optional.  It
  185.                   is required only when one address is in a net that is
  186.                   different from the address immediately in front of it.
  187.  
  188.                   These two lines have the same meaning:
  189.  
  190.                            SEEN-BY: 124/102 103 133/1
  191.  
  192.                            SEEN-BY: 124/102 124/103 133/1
  193.  
  194.                   The first example is preferred because it is shorter.  The
  195.                   NET for node 103 is inferred to be NET 124.
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.          None of these items is optional.  All EchoMail messages must
  203.          contain an AREA statement, a tearline, and origin line, and a 
  204.          sequence of 1 or more seen-by lines.
  205.  
  206.          Only the origination station is allowed to touch the tearline
  207.          and the origin line.  Some echomail processing methods depend on
  208.          the integrity of those items.  After a message leaves the 
  209.          originating node, only the seen-by line can be altered.
  210.  
  211.          Some echomail processors use a <cr/lf> combination as a hard
  212.          return.  In other words, the hard return can appear as "0d" or
  213.          as "0d 0a".
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.          RESERVED AREA NAMES
  221.          -------------------
  222.  
  223.          By convention, two area names are reserved...
  224.  
  225.                   PRIVATE ... the message should be sent to the area
  226.                               where the system normally keeps private
  227.                               e-mail.
  228.  
  229.                   GENERAL ... the message is for the general (local)
  230.                               message area.
  231.  
  232.          One possible use for the PRIVATE "area" is when a net host needs
  233.          to send messages to everyone in your net.  The host could use
  234.          echomail programs to handle this "bombing run."
  235.  
  236.          In practice, you may lead an entire life without ever seeing
  237.          a message for PRIVATE or GENERAL.
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244. MISCELLANEOUS
  245. -------------
  246.  
  247.  
  248.          CONTROL-A LINES
  249.          ---------------
  250.  
  251.          Material found after a CONTROL-A (hex 01) is considered a
  252.          control type sequence.  It is not part of the message itself.
  253.  
  254.          The general form of a CONTROL-A line looks like this:
  255.  
  256.                   ^aAAAAAAAA??????????????????<cr>
  257.  
  258.          That's a control-a, followed by one or more uppercase letters,
  259.          followed by some other information. 
  260.  
  261.          All CONTROL-A lines end with a hard return character (<cr> or
  262.          <cr/lf>).
  263.  
  264.          The CONTROL-A character (hex 01) signals the beginning of a
  265.          sequence.  The return character (hex 0d) signals its end.
  266.  
  267.          Following is an example of a ^a line's usage....
  268.  
  269.  
  270.  
  271.  
  272.          ECHOMAIL IDENTIFICATION
  273.          -----------------------
  274.  
  275.          Opus-Cbcs 1.00 puts an identification behind a CONTROL-A in
  276.          every echomail message processed internally.
  277.  
  278.          Here is the form of this identification:
  279.  
  280.                   ^aEID:xxxx xxxxxxxx
  281.  
  282.          That's a CONTROL-A followed by "EID:" and two hexidecimal 
  283.          numbers.  The first number is a 16-bit CRC of the originating
  284.          system's "*Origin" line.  The second number is an Ms-DOS style
  285.          time/date record.
  286.  
  287.          This item can be used to establish a unique identifier for every
  288.          message in the system.  Opus uses it as part of the system's
  289.          internal "Kill Dupe" feature.
  290.  
  291.  
  292.  
  293.  
  294.          CONTENT INTEGRITY
  295.          -----------------
  296.  
  297.          Echomail processing programs should not change the contents of
  298.          a message.
  299.  
  300.          The exceptions to that are
  301.  
  302.                   * addition of new SEEN-BY items
  303.  
  304.                   * addition of items hidden behind a "^a" 
  305.  
  306.          The content of the message body (ie the message itself) should
  307.          not be changed for any reason.
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314. SAMPLE
  315. ------
  316.  
  317. Here is a dump of a typical file ready for transmission.  It contains
  318. a single message in the echomail area "WALRUS."
  319.  
  320. This message was created using the Opus LORE (Line-oriented editor).
  321. It was "scanned" and put into the OUT file by OOMP (Official Opus
  322. Message Publisher... an internal scan feature in Opus-Cbcs v1.00).
  323.  
  324.  
  325.      0: 6c 00 66 00 c3 07 06 00  1b 00 09 00 06 00 18 00 l.f..... ........
  326.     10: 00 00 02 00 7c 00 7c 00  05 00 00 00 00 00 00 00 ....|.|. ........
  327.     20: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ........ ........
  328.     30: 00 00 00 00 00 00 00 00  00 00 02 00 6c 00 66 00 ........ ....l.f.
  329.     40: 7c 00 7c 00 00 00 00 00  32 37 20 4a 75 6e 20 38 |.|..... 27 Jun 8
  330.     50: 37 20 30 39 3a 30 35 3a  33 33 00 4e 6f 62 6f 64 7 09:05: 33.Nobod
  331.     60: 79 00 57 79 6e 6e 20 57  61 67 6e 65 72 00 2e 00 y.Wynn W agner...
  332.     70: 41 52 45 41 3a 57 41 4c  52 55 53 0d 0a 01 45 49 AREA:WAL RUS...EI
  333.     80: 44 3a 37 31 30 30 20 30  65 64 62 34 38 62 30 0d D:7100 0 edb48b0.
  334.     90: 8d 0a 54 68 69 73 20 69  73 20 61 20 74 65 73 74 ..This i s a test
  335.     a0: 20 6d 65 73 73 61 67 65  2e 0d 0a 0d 0a 0d 0a 2d message .......-
  336.     b0: 2d 2d 0d 0a 20 2a 20 4f  72 69 67 69 6e 3a 20 54 --.. * O rigin: T
  337.     c0: 68 65 20 50 72 69 76 61  74 65 20 4f 61 6b 20 4c he Priva te Oak L
  338.     d0: 61 77 6e 20 45 78 63 68  61 6e 67 65 20 28 4f 70 awn Exch ange (Op
  339.     e0: 75 73 20 31 3a 31 32 34  2f 31 30 38 29 0d 0a 53 us 1:124 /108)..S
  340.     f0: 45 45 4e 2d 42 59 3a 20  31 32 34 2f 31 30 32 20 EEN-BY:  124/102 
  341.    100: 31 30 38 20 31 31 31 20  32 31 30 20 31 33 32 2f 108 111  210 132/
  342.    110: 31 30 31 0d 0a 0d 0a 00  00 00                   101..... ..
  343.  
  344.  
  345.                                       ###
  346.  
  347.